Pulumi Project Layout

在昨天的文章中，介紹了如何安裝 Pulumi，並透過 pulumi new 指令建立專案、執行專案。今天就來聊聊，要滿足什麼條件才是一個 Pulumi 專案，並介紹一些 Pulumi 的術語。

Project file

首先我們來看一下使用 pulumi new typescript 的專案結構。
這是 Pulumi 的 TypeScript 專案範本預設會建立的檔案。

pulumi-hello-world-ts
├── Pulumi.dev.yaml
├── Pulumi.yaml
├── index.ts
├── package-lock.json
├── package.json
└── tsconfig.json

另外我們來看一下，如果是用 pulumi new python，會產生怎麼樣的專案結構：

./pulumi-hello-world-python
├── venv
├── Pulumi.dev.yaml
├── Pulumi.yaml
├── __main__.py
└── requirements.txt

可以發現，不管是使用 TypeScript 還是 Python 的範本，都會有兩個檔案在專案中，分別是 Pulumi.yaml 與 Pulumi.dev.yaml 這兩個檔案。

其中 Pulumi.yaml 是 Pulumi 的核心檔案，只要專案中有這個檔案，pulumi 就能識別到這個資料夾是一個 Pulumi 專案。
在官方文件中有提到，專案中必需要有大寫 P 開頭的 Pulumi 的 YAML 檔案，副檔名可以是 .yaml 或 .yml。

接著我們來看看 typescript 與 python 範本所產生的 Pulumi.yaml 的內容。

TypeScript 範本中的 Pulumi.yaml

name: pulumi-hello-world-ts
runtime: nodejs
description: A minimal TypeScript Pulumi program

Python 範本中的 Pulumi.yaml

name: pulumi-hello-world-python
runtime:
  name: python
  options:
    virtualenv: venv
description: A minimal Python Pulumi program

在 Pulumi.yaml 中，有兩個屬性是一定要有的 name 與 runtime。name 也就是這個專案的名稱，runtime 則是這個專案是使用什麼程式語言撰寫的。Pulumi 會透過這個 runtime 決定要怎麼執行專案中的程式。每個 runtime 可能還有 options 可以調整 runtime 執行的行為。

Pulumi.yaml 中還可以有其他的屬性，可以參閱官方文件。

Stack file

看完了 Pulumi.yaml 後，我們來看另一個也很重要的檔案：Pulumi.dev.yaml。

這個檔案是 Stack dev 的設定檔。昨天在使用 pulumi new 的時候，有要我們填入 stack name。Pulumi 預設會幫我們填入 dev，就會建立一個叫做 dev 的 Stack。而 Pulumi 會使用 Pulumi.<stack name>.yaml 做為 Stack 設定檔的檔名。

那麼什麼是 Stack 呢？

Stack 是 Pulumi 的一個部署單位，當我們想要將同樣的 IaC 專案，重複部署以產生不同的環境的時候，就可以創造不同的 Stack，並為每個不同的 Stack 設定屬於他的設定值。

官方建議，可以使用環境名稱做為 Stack 的名稱，例如：prod, stage, UAT, development 等。甚至如果有做 PR review app 之類的功能，也可以使用 git branch name 或是 PR number 做為 Stack 名稱，例如 feature-xxx, bugfix-a, PR-33, PR-155 等。

目前我們只要知道有 Pulumi.<stack name>.yaml 這個檔案即可，未來介紹到 Config 與 Secret 的時候，會再來看這個檔案的內容。

其他檔案呢？

除了 Pulumi.yaml 與 Pulumi.dev.yaml 以外的檔案，幾乎都是使用該程式語言會用到的檔案。

• TypeScript 專案中，就會有 package.json、package-lock.json 這兩個 Node.js 的專案檔。並且有一個 tsconfig.json TypeScript 的設定檔案。
  在 TypeScript / JavaScript 的專案中，Pulumi 會參考 package.json 中的 main 屬性，做為要執行的檔案。

• Python 專案的話，會有 venv 虛擬環境的資料夾、requirements.txt、__main.py__。Pulumi.yaml 會尋找 __main__.py，或是 setup.py 中的 entry_points。

• Java 專案分為使用 maven 做建置管理，或是 gradle，Pulumi 預設的 Java 範本是使用 maven 做為建置管理。

  • maven 會參考 pom.xml 中的 mainClass properties。
  • gradle 需要使用 application plugin，並設定 mainClass。Pulumi 會使用 gradle run 的方式執行專案

  當然如果要使用 Kotlin 撰寫也可以，只要編譯出來的 jar 檔，mainClass 的位置正確即可。

Stack 操作指令

本篇最後，介紹一些與 Stack 操作有關的指令。

刪除 Stack

要刪除 Stack 的第一件事是確保 Stack 中的資源皆已經刪除。我們可以透過 pulumi destroy 指令移除所有部署的資源。

$ pulumi destroy
Please choose a stack: dev
Previewing destroy (dev)

View in Browser (Ctrl+O): https://app.pulumi.com/xxxxxx/pulumi-hello-world/dev/previews/67612433-1307-42fb-8630-284453fd0976

     Type                      Name                       Plan
 -   pulumi:pulumi:Stack       pulumi-hello-world-ts-dev  delete
 -   └─ command:local:Command  hello,world                delete


Outputs:
  - helloWorldOutput: "hello,world"

Resources:
    - 2 to delete

Do you want to perform this destroy?  [Use arrows to move, type to filter]
> yes
  no
  details

刪除所有雲端資源後，可以看到最後指令輸出的地方也有提示，可以透過 pulumi stack rm dev 指令移除 Stack。

View in Browser (Ctrl+O): https://app.pulumi.com/xxxxxx/pulumi-hello-world-ts/dev/updates/2

     Type                      Name                       Status
 -   pulumi:pulumi:Stack       pulumi-hello-world-ts-dev  deleted
 -   └─ command:local:Command  hello,world                deleted (0.24s)


Outputs:
  - helloWorldOutput: "hello,world"

Resources:
    - 2 deleted

Duration: 2s

The resources in the stack have been deleted, but the history and configuration associated with the stack are still maintained.
If you want to remove the stack completely, run `pulumi stack rm dev`.

接著我們只要輸入 pulumi stack rm dev 就會將 Stack 移除。這個指令會移除所有 Stack 的紀錄，還有 dev Stack 的設定檔案，也就是 pulumi.dev.yaml 這個檔案。

pulumi stack rm dev
This will permanently remove the 'dev' stack!
Please confirm that this is what you'd like to do by typing `dev`:  dev
Stack 'dev' has been removed!

新增 Stack

刪除完 Stack 後，接著我們介紹如何把 Stack 加回來。

在沒有 Stack 的狀況下，執行 pulumi up 系統就會提示我們建立 Stack 了。

但如果已經有 Stack 想要建立更多的 Stack，就不能透過這個方式了。
正規的方式是要透過 pulumi stack init <stack name> 指令，新增一個 stack 。

例如：

$ pulumi stack init dev
Created stack 'dev'

接著藉由這個指令再新增 prod, stage 的 Stack。

$ pulumi stack init prod
Created stack 'prod'
$ pulumi stack init stage
Created stack 'stage'

列出所有 Stack

新增了這麼多 Stack 後，可以透過 pulumi stack ls 查詢有哪些 stack。
可以注意到，輸出的 stack name 後面會有一個 *，有這個標記的 Stack ，代表是預設 Stack。使用 pulumi up、pulumi destroy 等指令時，如果沒有指定 Stack 就會用這個預設 stack。

pulumi stack ls
NAME    LAST UPDATE  RESOURCE COUNT  URL
dev     n/a          n/a             https://app.pulumi.com/xxxxx/pulumi-hello-world-ts/dev
prod    n/a          n/a             https://app.pulumi.com/xxxxx/pulumi-hello-world-ts/prod
stage*  n/a          n/a             https://app.pulumi.com/xxxxx/pulumi-hello-world-ts/stage

當然也可以在 Pulumi Cloud 的 Stack 頁面看到所有 Project 與 Stack。

Notes:
如果剛剛建立完 Stack 有觀察資料夾狀態，一定會有個疑惑：「不是說會有一個 Stack 設定檔，叫做 Pulumi.<stack name>.yaml 嗎？怎麼資料夾中沒看到 Pulumi.dev.yaml, Pulumi.prod.yaml, Pulumi.stage.yaml？」。

這個原因是因為，我們建立了 Stack 後，並沒有設定任何的 config 或是 secret。因為沒有這些資料，因此也沒有必要有設定檔案了。
未來只要設定了 config 或 secret，Pulumi 就會自動生成 Stack 設定檔了。

更改預設的 Stack

前面講到，* 代表的是預設的 Stack，執行 pulumi up 或 pulumi destroy 都會預設使用這個 Stack。那如果希望更改預設的 Stack 要怎麼做呢？

使用 pulumi stack select <stack name> 指令，即可更改預設的 Stack 了！

可以看到以下輸出，將預設 Stack 變更為 dev 了。

$ pulumi stack select dev
$ pulumi stack ls
NAME   LAST UPDATE   RESOURCE COUNT  URL
dev*   n/a           n/a             https://app.pulumi.com/xxxxx/pulumi-hello-world-ts/dev
prod   n/a           n/a             https://app.pulumi.com/xxxxx/pulumi-hello-world-ts/prod
stage  1 minute ago  3               https://app.pulumi.com/xxxxx/pulumi-hello-world-ts/stage

取消預設 Stack

如果不想要讓 Pulumi 使用預設 Stack，希望在執行 pulumi up、pulumi destroy 指令時，提示使用者選擇 Stack 要怎麼做呢？

使用 pulumi stack unselect 即可取消預設 stack 了。

可以看到 pulumi stack ls 輸出中，沒有任何預設 stack 了。

$ pulumi stack unselect
Stack was unselected
$ pulumi stack ls
NAME   LAST UPDATE    RESOURCE COUNT  URL
dev    n/a            n/a             https://app.pulumi.com/xxxxx/pulumi-hello-world-ts/dev
prod   n/a            n/a             https://app.pulumi.com/xxxxx/pulumi-hello-world-ts/prod
stage  4 minutes ago  3               https://app.pulumi.com/xxxxx/pulumi-hello-world-ts/stage

以上就是今天關於 Pulumi 專案結構的介紹、以及 Stack 操作的內容。

明天我們就會開始使用 Pulumi 建立 AWS 的資源。